//
//  DMLifecycleUtils.h
//  DualMediationSDK
//
//  生命周期管理工具类
//  提供生命周期相关的辅助方法和工具函数
//

#import <Foundation/Foundation.h>
#import <UIKit/UIKit.h>
#import "../Types/DMLifecycleTypes.h"

NS_ASSUME_NONNULL_BEGIN

/**
 * 生命周期工具类
 * 提供生命周期状态检查、转换验证、调试信息等辅助功能
 */
@interface DMLifecycleUtils : NSObject

#pragma mark - 状态检查工具

/**
 * 检查当前应用是否处于前台状态
 * @return YES表示应用在前台，NO表示在后台或其他状态
 */
+ (BOOL)isApplicationInForeground;

/**
 * 检查当前应用是否处于活跃状态
 * @return YES表示应用活跃，NO表示非活跃
 */
+ (BOOL)isApplicationActive;

/**
 * 检查当前应用是否处于后台状态
 * @return YES表示应用在后台，NO表示在前台或其他状态
 */
+ (BOOL)isApplicationInBackground;

/**
 * 根据UIApplication状态获取对应的生命周期状态
 * @return 当前的生命周期状态
 */
+ (DMLifecycleState)currentLifecycleStateFromApplication;

#pragma mark - 状态转换工具

/**
 * 获取状态转换的建议事件
 * @param fromState 起始状态
 * @param toState 目标状态
 * @return 建议的触发事件，如果转换无效则返回DMLifecycleEventUnknown
 */
+ (DMLifecycleEvent)suggestedEventForTransitionFrom:(DMLifecycleState)fromState 
                                                 to:(DMLifecycleState)toState;

/**
 * 获取状态的可能转换目标列表
 * @param state 当前状态
 * @return 可能的转换目标状态数组
 */
+ (NSArray<NSNumber *> *)possibleTransitionsFromState:(DMLifecycleState)state;

/**
 * 检查状态转换路径是否有效
 * @param states 状态转换路径数组
 * @return YES表示路径有效，NO表示路径无效
 */
+ (BOOL)isValidTransitionPath:(NSArray<NSNumber *> *)states;

#pragma mark - 调试和日志工具

/**
 * 生成生命周期状态的详细描述
 * @param state 生命周期状态
 * @param includeTimestamp 是否包含时间戳
 * @return 详细描述字符串
 */
+ (NSString *)detailedDescriptionForState:(DMLifecycleState)state 
                         includeTimestamp:(BOOL)includeTimestamp;

/**
 * 生成生命周期事件的详细描述
 * @param event 生命周期事件
 * @param includeTimestamp 是否包含时间戳
 * @return 详细描述字符串
 */
+ (NSString *)detailedDescriptionForEvent:(DMLifecycleEvent)event 
                         includeTimestamp:(BOOL)includeTimestamp;

/**
 * 生成状态转换的日志信息
 * @param fromState 起始状态
 * @param toState 目标状态
 * @param event 触发事件
 * @param duration 转换耗时（秒）
 * @return 格式化的日志字符串
 */
+ (NSString *)transitionLogFromState:(DMLifecycleState)fromState 
                             toState:(DMLifecycleState)toState 
                           withEvent:(DMLifecycleEvent)event 
                            duration:(NSTimeInterval)duration;

#pragma mark - 性能监控工具

/**
 * 计算状态持续时间
 * @param startTime 状态开始时间
 * @param endTime 状态结束时间（nil表示当前时间）
 * @return 持续时间（秒）
 */
+ (NSTimeInterval)stateDurationFrom:(NSDate *)startTime 
                                 to:(nullable NSDate *)endTime;

/**
 * 格式化时间间隔为可读字符串
 * @param interval 时间间隔（秒）
 * @return 格式化的时间字符串
 */
+ (NSString *)formatTimeInterval:(NSTimeInterval)interval;

/**
 * 检查状态持续时间是否异常
 * @param state 生命周期状态
 * @param duration 持续时间（秒）
 * @return YES表示持续时间异常，NO表示正常
 */
+ (BOOL)isAbnormalDuration:(NSTimeInterval)duration forState:(DMLifecycleState)state;

#pragma mark - 配置和常量

/**
 * 获取状态的默认超时时间
 * @param state 生命周期状态
 * @return 超时时间（秒）
 */
+ (NSTimeInterval)defaultTimeoutForState:(DMLifecycleState)state;

/**
 * 获取事件的默认处理超时时间
 * @param event 生命周期事件
 * @return 超时时间（秒）
 */
+ (NSTimeInterval)defaultTimeoutForEvent:(DMLifecycleEvent)event;

/**
 * 获取生命周期管理的版本信息
 * @return 版本字符串
 */
+ (NSString *)lifecycleManagerVersion;

@end

NS_ASSUME_NONNULL_END